---
title: MCP 客户端
description: 学习如何使用模型上下文协议（MCP）客户端与 MCP 服务器交互
---

# 模型上下文协议客户端

MCP 客户端是模型上下文协议（MCP）架构中的关键组件，负责与 MCP 服务器建立和管理连接。它实现了协议的客户端部分，处理以下内容：

- 协议版本协商以确保与服务器的兼容性
- 能力协商以确定可用功能
- 消息传输和 JSON-RPC 通信
- 工具发现和执行
- 资源访问和管理
- 提示系统交互
- 可选功能，如根路径管理和采样支持

<Tip>
核心 `io.modelcontextprotocol.sdk:mcp` 模块提供了标准输入输出和 SSE 客户端传输实现，无需外部 Web 框架。

对于 [Spring 框架](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html) 用户，可选择添加 **可选** 依赖 `io.modelcontextprotocol.sdk:mcp-spring-webflux` 以使用 Spring 特定的传输实现。
</Tip>

客户端提供同步和异步 API，以适应不同的应用场景。

<Tabs>
  <Tab title="同步 API">
```java
// 使用自定义配置创建同步客户端
McpSyncClient client = McpClient.sync(transport)
    .requestTimeout(Duration.ofSeconds(10))
    .capabilities(ClientCapabilities.builder()
        .roots(true)      // 启用根路径功能
        .sampling()       // 启用采样功能
        .build())
    .sampling(request -> new CreateMessageResult(response))
    .build();

// 初始化连接
client.initialize();

// 列出可用工具
ListToolsResult tools = client.listTools();

// 调用工具
CallToolResult result = client.callTool(
    new CallToolRequest("calculator", 
        Map.of("operation", "add", "a", 2, "b", 3))
);

// 列出和读取资源
ListResourcesResult resources = client.listResources();
ReadResourceResult resource = client.readResource(
    new ReadResourceRequest("resource://uri")
);

// 列出和使用提示
ListPromptsResult prompts = client.listPrompts();
GetPromptResult prompt = client.getPrompt(
    new GetPromptRequest("greeting", Map.of("name", "Spring"))
);

// 添加/删除根路径
client.addRoot(new Root("file:///path", "描述"));
client.removeRoot("file:///path");

// 优雅关闭客户端
client.closeGracefully();
```
  </Tab>

  <Tab title="异步 API">
```java
// 使用自定义配置创建异步客户端
McpAsyncClient client = McpClient.async(transport)
    .requestTimeout(Duration.ofSeconds(10))
    .capabilities(ClientCapabilities.builder()
        .roots(true)      // 启用根路径功能
        .sampling()       // 启用采样功能
        .build())
    .sampling(request -> Mono.just(new CreateMessageResult(response)))
    .toolsChangeConsumer(tools -> Mono.fromRunnable(() -> {
        logger.info("工具已更新: {}", tools);
    }))
    .resourcesChangeConsumer(resources -> Mono.fromRunnable(() -> {
        logger.info("资源已更新: {}", resources);
    }))
    .promptsChangeConsumer(prompts -> Mono.fromRunnable(() -> {
        logger.info("提示已更新: {}", prompts);
    }))
    .build();

// 初始化连接并使用功能
client.initialize()
    .flatMap(initResult -> client.listTools())
    .flatMap(tools -> {
        return client.callTool(new CallToolRequest(
            "calculator", 
            Map.of("operation", "add", "a", 2, "b", 3)
        ));
    })
    .flatMap(result -> {
        return client.listResources()
            .flatMap(resources -> 
                client.readResource(new ReadResourceRequest("resource://uri"))
            );
    })
    .flatMap(resource -> {
        return client.listPrompts()
            .flatMap(prompts ->
                client.getPrompt(new GetPromptRequest(
                    "greeting", 
                    Map.of("name", "Spring")
                ))
            );
    })
    .flatMap(prompt -> {
        return client.addRoot(new Root("file:///path", "描述"))
            .then(client.removeRoot("file:///path"));            
    })
    .doFinally(signalType -> {
        client.closeGracefully().subscribe();
    })
    .subscribe();
```
  </Tab>
</Tabs>

## 客户端传输

传输层负责处理 MCP 客户端与服务器之间的通信，为不同用例提供多种实现。客户端传输管理消息序列化、连接建立和协议特定的通信模式。

<Tabs>
    <Tab title="标准输入输出">
        创建基于进程通信的传输
        ```java
        ServerParameters params = ServerParameters.builder("npx")
            .args("-y", "@modelcontextprotocol/server-everything", "dir")
            .build();
        McpTransport transport = new StdioClientTransport(params);
        ```
    </Tab>
    <Tab title="SSE (HttpClient)">
        创建不依赖框架（纯 Java API）的 SSE 客户端传输。包含在核心 mcp 模块中。
        ```java
        McpTransport transport = new HttpClientSseClientTransport("http://your-mcp-server");
        ```
    </Tab>
    <Tab title="SSE (WebFlux)">
        创建基于 WebFlux 的 SSE 客户端传输。需要 mcp-webflux-sse-transport 依赖。
        ```java
        WebClient.Builder webClientBuilder = WebClient.builder()
            .baseUrl("http://your-mcp-server");
        McpTransport transport = new WebFluxSseClientTransport(webClientBuilder);
        ```
    </Tab>
</Tabs>

## 客户端功能

客户端可以配置多种功能：

```java
var capabilities = ClientCapabilities.builder()
    .roots(true)      // 启用文件系统根路径支持，并包含列表变更通知
    .sampling()       // 启用大语言模型采样支持
    .build();
```

### 根路径支持

根路径定义了服务器在文件系统中的操作范围：

```java
// 动态添加根路径
client.addRoot(new Root("file:///path", "描述"));

// 删除根路径
client.removeRoot("file:///path");

// 通知服务器根路径列表变更
client.rootsListChangedNotification();
```

根路径功能允许服务器：

- 请求可访问的文件系统根路径列表
- 接收根路径列表变更通知
- 了解它们有权访问的目录和文件

### 采样支持

采样使服务器能够通过客户端请求大语言模型交互（“补全”或“生成”）：

```java
// 配置采样处理程序
Function<CreateMessageRequest, CreateMessageResult> samplingHandler = request -> {
    // 与大语言模型交互的采样实现
    return new CreateMessageResult(response);
};

// 创建支持采样的客户端
var client = McpClient.sync(transport)
    .capabilities(ClientCapabilities.builder()
        .sampling()
        .build())
    .sampling(samplingHandler)
    .build();
```

此功能允许：
- 服务器无需 API 密钥即可利用 AI 功能
- 客户端保持对模型访问和权限的控制
- 支持基于文本和图像的交互
- 可选择在提示中包含 MCP 服务器上下文

### 日志支持

客户端可以注册日志消费者以接收来自服务器的日志消息，并设置最低日志级别以过滤消息：

```java	
var mcpClient = McpClient.sync(transport)
        .loggingConsumer(notification -> {
            System.out.println("收到日志消息: " + notification.data());
        })
        .build();

mcpClient.initialize();

mcpClient.setLoggingLevel(McpSchema.LoggingLevel.INFO);

// 调用可发送日志通知的工具
CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("logging-test", Map.of()));
```
客户端可以通过 `mcpClient.setLoggingLevel(level)` 请求控制接收的最低日志级别。低于设定级别的消息将被过滤。
支持的日志级别（按严重程度递增）：DEBUG (0)、INFO (1)、NOTICE (2)、WARNING (3)、ERROR (4)、CRITICAL (5)、ALERT (6)、EMERGENCY (7)

## 使用 MCP 客户端

### 工具执行

工具是服务器端的函数，客户端可以发现并执行它们。MCP 客户端提供了列出可用工具并使用特定参数执行它们的方法。每个工具都有唯一的名称并接受参数映射。

<Tabs>
  <Tab title="同步 API">
```java
// 列出可用工具及其名称
var tools = client.listTools();
tools.forEach(tool -> System.out.println(tool.getName()));

// 使用参数执行工具
var result = client.callTool("calculator", Map.of(
    "operation", "add",
    "a", 1,
    "b", 2
));
```
  </Tab>

  <Tab title="异步 API">
```java
// 异步列出可用工具
client.listTools()
    .doOnNext(tools -> tools.forEach(tool -> 
        System.out.println(tool.getName())))
    .subscribe();

// 异步执行工具
client.callTool("calculator", Map.of(
        "operation", "add",
        "a", 1,
        "b", 2
    ))
    .subscribe();
```
  </Tab>
</Tabs>

### 资源访问

资源表示客户端可以通过 URI 模板访问的服务器端数据源。MCP 客户端提供了发现可用资源并通过标准化接口检索其内容的方法。

<Tabs>
  <Tab title="同步 API">
```java
// 列出可用资源及其名称
var resources = client.listResources();
resources.forEach(resource -> System.out.println(resource.getName()));

// 使用 URI 模板检索资源内容
var content = client.getResource("file", Map.of(
    "path", "/path/to/file.txt"
));
```
  </Tab>

  <Tab title="异步 API">
```java
// 异步列出可用资源
client.listResources()
    .doOnNext(resources -> resources.forEach(resource -> 
        System.out.println(resource.getName())))
    .subscribe();

// 异步检索资源内容
client.getResource("file", Map.of(
        "path", "/path/to/file.txt"
    ))
    .subscribe();
```
  </Tab>
</Tabs>

### 提示系统

提示系统支持与服务器端提示模板的交互。这些模板可以被发现并使用自定义参数执行，允许基于预定义模式进行动态文本生成。

<Tabs>
  <Tab title="同步 API">
```java
// 列出可用提示模板
var prompts = client.listPrompts();
prompts.forEach(prompt -> System.out.println(prompt.getName()));

// 使用参数执行提示模板
var response = client.executePrompt("echo", Map.of(
    "text", "你好，世界！"
));
```
  </Tab>

  <Tab title="异步 API">
```java
// 异步列出可用提示模板
client.listPrompts()
    .doOnNext(prompts -> prompts.forEach(prompt -> 
        System.out.println(prompt.getName())))
    .subscribe();

// 异步执行提示模板
client.executePrompt("echo", Map.of(
        "text", "你好，世界！"
    ))
    .subscribe();
```
  </Tab>
</Tabs>
